home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / cjdates.exe / DATES.DOC < prev    next >
Text File  |  1991-07-26  |  39KB  |  897 lines
  1.  
  2.  
  3.  
  4.  
  5.                            CRAZY JACK'S DATE ROUTINES
  6.                                   USER'S GUIDE
  7.  
  8.                          (c)Copyright 1991 by Crazy Jack
  9.                                All Rights Reserved
  10.  
  11.                                      NOTICE
  12.  
  13.         This is NOT Public Domain software!  You don't have to pay for it
  14.         (except for distribution costs) but it IS copyrighted.   You  may
  15.         not sell or distribute the ZDay and ZDate routines or the various
  16.         header,  "include", documentation or example files for any charge
  17.         beyond  what is currently customary for "shareware" distribution,
  18.         but you may freely incorporate them into your own software  with-
  19.         out  further  charge or royalties.   In other  words,  use  Crazy
  20.         Jack's Date Routines freely, but don't steal.
  21.  
  22.         Crazy  Jack's Date Routines may only be distributed as  a  single
  23.         package containing the following 14 files:
  24.  
  25.              READ.ME        Introductory remarks and instructions.
  26.              DATES.DOC      The User's Guide (this file).
  27.              DATES.ASM      The Date Routines assembler source.
  28.              DATES.LST      The assembly listing.
  29.              DATES.OBJ      The assembled object module.
  30.              DATES.PAS      The Turbo Pascal unit source code.
  31.              DATES.TPU      The Turbo Pascal v6.0 compiled unit.
  32.              DATES.INC      Additional Turbo Pascal source code.
  33.              DATES.H        C header for date routines.
  34.              DATENAMS.C     Additional C source code for #including.
  35.              DTP.PAS        Turbo Pascal date routines demo source code.
  36.              DTP.EXE        Compiled Turbo Pascal date routines demo.
  37.              DTC.C          Borland C++ C date routines demo source code.
  38.              DTC.EXE        C date routines demo, ready-to-run.
  39.  
  40.         If you wish to make changes, go ahead, BUT:
  41.  
  42.         1.)             If  you  distribute the result,  it must be done  under  the
  43.              rules described in this notice.
  44.         2.)             Leave  the original copyright notices intact;  do not remove
  45.              existing material.
  46.         3.)             Add your own copyright notices where appropriate.
  47.         4.)             Clearly indicate where you have made changes.
  48.  
  49.         Turbo Pascal,  Borland C++ and Paradox are trademarks of  Borland
  50.         International.
  51.  
  52.  
  53.                                            1
  54.  
  55.         CRAZY JACK'S DATE ROUTINES                           USER'S GUIDE
  56.  
  57.  
  58.         This material has no warranties, expressed or implied as to suit-
  59.         ability for any particular task.
  60.  
  61.         Let's face it,  gang, even when it's theoretically possible, it's
  62.         usually  not practical to test most software exhaustively  or  to
  63.         prove its perfection.   Further, as in the case of this software,
  64.         assumptions  are made that are not true for all possible  inputs.
  65.         For  example,  no  one knows what kind of calendar may be in  use
  66.         10000 years from now (if any),  and Gregorian dates have no mean-
  67.         ing in the period before the Gregorian calendar was adopted.  (It
  68.         was adopted at different times in different places!)  The  number
  69.         of  days between two dates always includes weekends and holidays;
  70.         you'll  have to determine the number of business  days  yourself.
  71.         And  so-on.   Only a fool will use any piece of software  without
  72.         testing  it  for suitability first.   Since you're getting  these
  73.         routines for distribution charges only,  what's your beef?   Any-
  74.         way,  I've included the source code so you can "fix" anything you
  75.         don't like (at your own risk, of course).
  76.  
  77.         The code was assembled with the Turbo Assembler v2.5 and works as
  78.         I  intended  with  programs written in Borland C++ v1.0  (ANSI  C
  79.         mode) and Turbo Pascal v6.0 (so far).
  80.  
  81.                                SO WHAT GOOD IS IT?
  82.  
  83.         For periods covered by the Gregorian calendar, these routines can
  84.         be  used  to determine the day of the week for a given  date,  to
  85.         convert between Gregorian and Julian dates, to validate Gregorian
  86.         dates (Is 2/29/1900 a valid date?   No, by the Gregorian 400-year
  87.         rule that was NOT a leap year!),  to determine the number of days
  88.         between  two dates,  and to find a date some number of days  from
  89.         another date.
  90.  
  91.         Since there are 36524 or 36525 years per century,  by subtracting
  92.         a base Day Number from the Day Numbers your dates yield,  you can
  93.         represent  a range of a bit over 179 years in a  16-bit  unsigned
  94.         integer (Turbo Pascal "word").
  95.  
  96.         By storing your dates as Day Numbers you simplify the comparison,
  97.         testing and sorting of dates.   By using the Day Number as an in-
  98.         dex  into a suitably constructed bit table you can determine if a
  99.         day is a special date such as a holiday.
  100.  
  101.         The  monotonic nature of the Day Numbers eliminates the need  for
  102.         century break testing, something that will soon be a problem.
  103.  
  104.  
  105.  
  106.                                            2
  107.  
  108.         CRAZY JACK'S DATE ROUTINES                           USER'S GUIDE
  109.  
  110.  
  111.                                   INSTALLATION
  112.  
  113.         TURBO PASCAL:
  114.  
  115.         If you use TP v6.0, just copy DATES.TPU into your TPU library and
  116.         DATES.INC  into the library where you keep frequently  used  $In-
  117.         clude files.  (You DO have such a library, don't you?)
  118.  
  119.         Those of you with other versions will have to compile the TPU for
  120.         your version.  Place DATES.OBJ and DATES.PAS into the same subdi-
  121.         rectory on some drive (your RAM disk is a nice place).  Make this
  122.         the  default drive and subdirectory.   Execute your version of TP
  123.         and  load DATES.PAS.   Set up to compile to disk,  then  compile.
  124.         Copy  the  resulting  DATES.TPU  into  your  TPU  library.   Copy
  125.         DATES.INC into your $Includes library, and you're ready to go.
  126.  
  127.         Borland C:
  128.  
  129.         Copy DATES.OBJ into your object library where the linker can find
  130.         it.   Copy DATES.H into your header library,  and copy DATENAMS.C
  131.         into your #include library.
  132.  
  133.                               THE MECHANICS OF USE
  134.  
  135.         TURBO PASCAL:
  136.  
  137.         You'll  need  a  "uses" statement that calls out "Dates"  so  the
  138.         DATES.TPU will be accessed.   If you need the additional routines
  139.         in DATES.INC, you can use either a {$I dates.inc} statement some-
  140.         where before you use the routines.   Or copy DATES.INC into  your
  141.         source code and remove the routines you don't need, or alter them
  142.         to suit; for example, you might change day and month names to all
  143.         upper  case,  or  change the month and weekday names  to  another
  144.         language.
  145.  
  146.         Borland C:
  147.  
  148.         Put  a #include statement for "dates.h" in the front of each  mo-
  149.         dule  in which you use date routines.   If you are using DOW() or
  150.         MonthName(),  remember  to  #include or copy (and alter  to  suit
  151.         yourself) DATENAMS.C into one of the modules so the code will get
  152.         compiled somewhere.  YDay() is defined as a macro in DATES.H, and
  153.         DATES.OBJ supplies the code for ZDay() and ZDate().  You must put
  154.         an  entry  for DATES.OBJ in your project file,  or in  your  make
  155.         file's link command or response file, or wherever is needed so it
  156.         will be linked.
  157.  
  158.  
  159.                                            3
  160.  
  161.         CRAZY JACK'S DATE ROUTINES                           USER'S GUIDE
  162.  
  163.  
  164.                               USING ZDAY AND ZDATE
  165.  
  166.         These are the routines for converting Gregorian dates to and from
  167.         Day Numbers.   They are called using the PASCAL calling sequence,
  168.         and are FAR calls.  All pointers are FAR pointers.
  169.  
  170.         They  can be used with both Borland C and Turbo Pascal  programs.
  171.         The header file DATES.H defines the interface for Borlan